Welcome to the GeoServer documentation process, this page will help you know what documentation we expect (before your work can be merged onto trunk), and what

guidelines we would like you to follow when writing

 This page will try and be as explicit as possible:

• Indicate your target audience, their skill level, what you can assume they know, etc...
• Writing guidelines, where appropriate, are actually going to be fairly strict
• Confluence conventions, such as nesting pages for table of contents

This should help save time:

• your time when writing
• your readers time when they are learning

Structure

The structure of all documents is Parent/Child.
We use the child's titles, and their children's as well, to display tables of contents. So it is important that your page fits in to the hierarchy of parent and child relationships, so put it somewhere that makes sense. If you are unsure of the proper place feel free to ask, or just guess and someone else can move it later.

Often you will see documentation pages prefixed by a number in their name. This will order the pages when the parent requests the children.

Goals and Assumptions

Documentation Targets

We want to accomplish the following tasks with our documentation:

• introduce and set up a new geoserver developer
• capture the big picture for those planning new services
• capture policy and procedures used by the community to forward the GeoServer product

Target Audience

We want to target the following users (names chosen because you know these people):

Oliver:

• *- Oliver is a new geoserver developer with a background in Java
  • He has some J2EE experience (knows what a servlet is) - is willing to learn more
  • Oliver is starting to learn patterns
  • He is working with the code base to either fix a bug or package up geoserver for a custom application.
  • Oliver has met XML and XML Schema before but will need an introduction to OGC web services such as WMS and WFS.

• Gabriel - Gabriel is a long time GeoServer contributor with an understanding of the GeoTools library, he has been responsible for setting up the WMS service. Gabriel will be checking the documentation to find out the big pictures. Some of the big picture is new (done last week), and some of it may be old (done on a project he was not involved with).
• Brent - Brent is a GeoServer developer that often volunteers to make GeoServer releases. He will be consulting the procedures for checklists to follow when accepting patches, granting committer status or releasing a new version of GeoServer. Brent's big fear is being left to maintain your work, so these procedures are designed to ensure that your work is good, and that he can interact with the community smoothly and fairly.

We thank the members of the community mentioned above for their patience/acceptance.

Confluence Content

While working on this wiki please observe the following.

Table of Contents

• Use of Parent/Child relationships for Table of Contents, to display a table of contents do the following:

  h2. Table of Contents
  {children:excerpt=true|style=h3|depth=2}
  

You can change parent / child relationshps while editing a page.

Excerpts macro

The excerpts macro can be used to provided a summary of each page, this is really helpful
when looking at content in a table of contents.

This page is about {excerpt}care and feeding of epsg-wkt plugin{excerpt}.

Rather then go out of your way just stick the macro around some random text that looks about right.

Use of Pictures

Please use png files where possible, gif files tend to degrate especially for screen snapshots or
examples of spatial data.

!diagram.png!

Use of Examples and Tips

Confluence provides several useful "panels":

• {panel}
• {no format} for command line examples
• {code} for java sample code
• {tip}, {warning}, {note}, {info} as required

You can use title as with the following example:

Writing Guidelines

1 Development Environment

• Target: Oliver
• Goal: setup the tools needed to work on Geoserver
• Content: procedures

Specifics:

• This section is the start, we need to build confidence:
  • One screen snap or code example per page, no big blobs of text (Oliver will fall aleep or skip ahead to the code example)
  • This section needs to be good, anything that is wrong or out of date will simply prevent a Oliver from starting, and chances are he goes onto the next open source project on his list
• Eclipse
  • assume Oliver has limitied familiarty with Eclipss
  • provide one screen snapshot per page, so Oliver can tell he is in the right spot
• Procedures
  • As setting up your development environment is a procedure you will need to provided a numbered list of steps for Oliver to follow.
  • Provide a checklist at the top of the page

Sample Development Environment Page

In this section you will {excerpt}sign up for email
and introduce yourself{excerpt}:
* sign up to geoserver-devel email list
* send an initial greeting

h2. Join the Community

Welcome to the community, a great first step is meeting
everyone else:
# Please visit the the mailing lists on sourceforge:
#* http://sourceforge.net/mail/?group_id=25086]
# Several email lists are available we are going to
  subscribe to the *geoserver-devel*
#* Click on
   http://lists.sourceforge.net/mailman/listinfo/geoserver-devel
#* fill in the provided form with your email address and so on
# A confirmation message will be sent out which may reply to in
  order to subscribe

Congratuations and welcome to the rough and ready world of
geoserver development.

h2. Introductions

While you are welcome to lurk on the email list, chances are you
here to accomplish something. Please introduce yourself and try
and include a little background on what you would like
to accomplish.

!email.png!

2 Building

Target Audience is someone who is a developer but junior, This area is to show the person how to build and debug Geoserver Also this will show the developer how to setup Geoserver with eclipse.

• Target: Oliver
• Goal: use the tools to set up a running geoserver
• Content: procedures

Specifics:

• Once again tread carefully, this is the most important part where we win or lose a new developer!
  • One screen snap or code example per page
  • no big blobs of text (Oliver will fall aleep or skip ahead to the code example)
  • This section needs to be good, anything that is wrong, throws a strack trace, or out of date will be bad
• Maven 2
  • do not assume Oliver knows Maven 2, or that he cares to know how it works
  • any maven task will need a command line example
  • optional: you may provide sample output
• Eclipse
  • assume Oliver has limitied familiarty with Eclipse
  • provide one screen snapshot per page, so Olver can tell he is in the right spot
• Procedures
  • As setting up your development environment is a procedure you will need to provided a numbered list of steps for Oliver to follow.
  • Provide a checklist at the top of the page

Sample Building Page

Using Maven 2 to {excerpt}run geoserver and open the
config ui{excerpt}:
* run geoserver
* open config ui

h2. Running GeoServer using Maven 2

To run GeoServer please use the following command:
{ noformat }
mvn jetty6:run
{ noformat }

Expect the following output:
{ noformat }
..end of sample output where it is waiting on port 8080...
{ noformat }

h2. Connect with the Web Configuration UI

Now that geoserver is running you can connect to the
configuration ui, as with the normal user guide instructions:

!starting.png!

Congradulations you have a working GeoServer!

mvn jetty6:run

..end of sample output where it is waiting on port 8080...

3 Development

Target Audience is someone is the geoserver developer, but someone relatively new to the community The Geoserver developer will document what he/she has done, however the Geoserver developer will not Justifiy what has done, just explain, justification will confuse the target audience If justification is needed add it to the Article section.

4 Architecture and Design

Target Audience is the Brent + Gabriels of the world Article stuff goes here VFS stuff goes here

5 FAQ's

Target Audience is Beginner to Intermediate Here you will post Email question and answers to those emails If a question is ask more than once, Write a wikki pg and send the link to the list, instead of answering again There question are organised by modules

6 How to's

Target Audience is Beginner to Intermediate This area is like tasks in Eclipse

7 Policies and Procedures

Target Audience is someone who will hack around and have intensive knowledge of Geoserver Core What goes in here? Release Procedures Other important stuff

edit.png (image/png)
email.png (image/png)
email.png (image/png)